COMMENT ⊗   VALID 00002 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	%Start Part 3 of 8 functi.tex
C00039 ENDMK
C⊗;
%Start Part 3 of 8 functi.tex



\begincom{defgeneric}\ftype{Macro}

\label Purpose:

The macro {\bf defgeneric} is used to define a generic function or to
specify options and declarations that pertain to a generic function as
a whole.

If {\tt (fboundp {\it function-specifier\/})} is {\bf nil}, a new
generic function is created.  If {\tt (symbol-function {\it
function-specifier\/})} is a generic function, that generic function
is modified.  If {\it function-specifier\/} names a non-generic
function, a macro, or a special form, an error is signaled.

Each {\it method-description\/} defines a method on the generic function.
The lambda-list of each method must be congruent with the lambda-list
specified by the {\it lambda-list\/} option.  If this condition
does not hold, an error is signaled.  See the section ``Congruent
Lambda-Lists for All Methods of a Generic Function'' for a definition
of congruence in this context.

The macro {\bf defgeneric} returns the generic function object 
as its result.

\label Syntax:

\Defmac {defgeneric} {function-specifier lambda-list\/ $\lbrack\!\lbrack\downarrow\!$ option $\vert$ \star{method-description} $\rbrack\!\rbrack$}

{\it function-specifier\/}::$=$ \curly{{\it symbol\/} $\vert$ {\tt (setf {\it symbol\/})}}
\Vskip 1pc!
\settabs\+\hskip\leftskip&\cr
\+&{\it lambda-list\/}::$=$ (&\star{\curly{var}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var\/{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var\/{\rm )}}{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} {\rm )} \cr
\Vskip 1pc!
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order \plus{\curly{parameter-name}}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} \star{\curly{arg\/}}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
\Vskip 1pc!
{\it method-description\/}::$=$ {\tt (:method}
\vtop{\hbox{\it \star{\curly{method-qualifier\/}} specialized-lambda-list\/}
\hbox{\star{\curly{declaration\/ $\vert$ documentation\/}} \star{\curly{form\/}}{\tt )}}}
\Vskip1pc!\null
{\it method-qualifier\/}::$=$ {\it non-nil-atom}
\vfill\eject
%\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var parameter-specializer-name\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\settabs\+\hskip\leftskip&\cr
\Vskip1pc!\null
\+&{\it parameter-specializer-name\/}::$=$ {\it symbol} $\vert$ {\rm (}{\tt eql} {\it eql-specializer-form\/}{\rm )}\cr
\Vskip 1pc!

\label Arguments:

The {\it function-specifier} argument is a non-{\bf nil} symbol or a
list of the form {\tt (setf {\it symbol\/})}.

The {\it lambda-list\/} argument is an ordinary function lambda-list
with these exceptions:

\beginlist
\item{\bull}
The use of {\bf \&aux} is not allowed. 

\item{\bull}
Optional and keyword arguments may not have default initial value forms
nor use supplied-p parameters.
The generic function passes to the method all the argument values passed to
it, and only those; default values are not supported.
Note that optional and keyword arguments in method definitions, however,
can have default initial value forms and can use supplied-p parameters. 
\endlist

The following options are provided.  A given option may occur only once,
or an error is signaled.

\beginlist
 
\item{\bull} 
The {\bf :argument-precedence-order} option is used to specify the
order in which the required arguments in a call to the generic
function are tested for specificity when selecting a particular
method.  Each required argument, as specified in the {\it lambda-list\/}
argument, must be included exactly once as a {\it
parameter-name} so that the full and unambiguous precedence order is
supplied.  If this condition is not met, an error is signaled.

\item{\bull}
The {\bf declare} option is used to specify declarations that pertain
to the generic function.  The following standard Common Lisp
declaration is allowed:

\itemitem{--}
An {\bf optimize} declaration specifies whether method selection
should be optimized for speed or space, but it has no effect on
methods.  To control how a method is optimized, an {\bf optimize}
declaration must be placed directly in the {\bf defmethod} form or
method description.  The optimization qualities {\bf speed} and {\bf
space} are the only qualities this standard requires, but an
implementation can extend the \CLOS\ to recognize other qualities.  A
simple implementation that has only one method selection technique and
ignores the {\bf optimize} declaration is valid.

\item{}
The {\bf special}, {\bf ftype}, {\bf function}, {\bf inline}, {\bf
notinline}, and {\bf declaration} declarations are not permitted.
Individual implementations can extend the {\bf declare} option to
support additional declarations.  If an implementation notices a
declaration that it does not support and that has not been proclaimed
as a non-standard declaration name in a {\bf declaration} proclamation, it
should issue a warning.

\item{\bull} 
The {\bf :documentation} argument associates a documentation string
with the generic function.  The documentation type for this string is
{\bf function}.  The form {\tt (documentation {\it
function-specifier\/} 'function)} may be used to retrieve this
string.

\item{\bull} 
The {\bf :generic-function-class} option may be used to specify that
the generic function is to have a different class than the default
provided by the system (the class {\bf standard-generic-function}).
The {\it class-name\/} argument is the name of a class that can be the
class of a generic function.  If {\it function-specifier\/} specifies
an existing generic function that has a different value for the {\bf
:generic-function-class} argument and the new generic function class
is compatible with the old, {\bf change-class} is called to change the
class of the generic function; otherwise an error is signaled.

\item{\bull} 
The {\bf :method-class} option is used to specify that all methods on
this generic function are to have a different class from the default
provided by the system (the class {\bf standard-method}).  The {\it
class-name\/} argument is the name of a class that is capable of being
the class of a method.

\item{\bull} 
The {\bf :method-combination} option is followed by a symbol that
names a type of method combination.  The arguments (if any) that
follow that symbol depend on the type of method combination.  Note
that the standard method combination type does not support any
arguments.  However, all types of method combination defined by the
short form of {\bf define-method-combination} accept an optional
argument named {\it order\/}, defaulting to {\bf
:most-specific-first}, where a value of {\bf :most-specific-last} reverses
the order of the primary methods without affecting the order of the
auxiliary methods.

\endlist

The {\it method-description\/} arguments define methods that will
be associated with the generic function.  The {\it method-qualifier}
and {\it specialized-lambda-list} arguments in a method description
are the same as for {\bf defmethod}.

The {\it form\/} arguments specify the method body.  The body of the
method is enclosed in an implicit block.  If {\it
function-specifier\/} is a symbol, this block bears the same name as
the generic function.  If {\it function-specifier\/} is a list of the
form {\tt (setf {\it symbol\/})}, the name of the block is {\it
symbol}.  

\label Values:

The generic function object is returned as the result. 

\label Remarks:

The effect of the {\bf defgeneric} macro is as if the following three
steps were performed: first, methods defined by previous {\bf
defgeneric} forms are removed; second, {\bf ensure-generic-function}
is called; and finally, methods specified by the current {\bf
defgeneric} form are added to the generic function. 

If no method descriptions are specified and a generic function of the same
name does not already exist, a generic function with no methods is created.

\vfill\eject
The {\it lambda-list\/} argument of {\bf
defgeneric} specifies the shape of lambda-lists for the methods on
this generic function.  All methods on the resulting generic function must have
lambda-lists that are congruent with this shape.  If a {\bf
defgeneric} form is evaluated and some methods for that generic
function have lambda-lists that are not congruent with that given in
the {\bf defgeneric} form, an error is signaled.  For further details
on method congruence, see ``Congruent Lambda-Lists for All Methods of
a Generic Function''

Implementations can extend {\bf defgeneric} to include other options.
It is required that an implementation signal an error if
it observes an option that is not implemented locally.

\label See Also:

``Congruent Lambda-Lists for All Methods of a Generic Function'' 

{\bf defmethod

ensure-generic-function

generic-function}

\endcom




\begincom{define-method-combination}\ftype{Macro}

\label Purpose:

The macro {\bf define-method-combination} is used to define new types
of method combination.

There are two forms of {\bf define-method-combination}.  The short
form is a simple facility for the cases that are expected
to be most commonly needed.  The long form is more powerful but more
verbose.  It resembles {\bf defmacro} in that the body is an
expression, usually using backquote, that computes a Lisp form.  Thus
arbitrary control structures can be implemented.  The long form also
allows arbitrary processing of method qualifiers.

\label Syntax:

\Defmac {define-method-combination} {name
 $\lbrack\!\lbrack\downarrow\!$ short-form-option $\rbrack\!\rbrack$}
\Vskip 1pc!
{\it short-form-option\/}::$=$ {\tt\vtop{\hbox{:documentation {\it string\/} $\vert$}
\hbox{:identity-with-one-argument {\it boolean\/} $\vert$}
\hbox{:operator {\it operator\/} $\vert$}}}
\Vskip1pc!

\Defmac {define-method-combination} {\vtop{\hbox{name lambda-list }
\hbox{\paren{\star{\curly{method-group-specifier}}} }
\hbox{\brac{\paren{{\tt :arguments .} {\it lambda-list }}}}
\hbox{\brac{\paren{{\tt :generic-function} {\it generic-function-symbol }}}}
\hbox{\star{\curly {declaration $\vert$ doc-string}}}
\hbox{\star{\curly{form}}}}}
\vbox
{\halign {\hskip \leftskip#\hfil&#\hfil\cr
{\it method-group-specifier\/}::$=$ (&{\it variable\/}
\curly{\plus{\curly{qualifier-pattern}} $\vert$ predicate}\cr
& $\lbrack\!\lbrack\downarrow\!$ {\it long-form-option\/} $\rbrack\!\rbrack$)\cr}}
\Vskip 1pc!
{\it long-form-option\/}::$=$ {\tt\vtop{\hbox{:description {\it format-string\/} $\vert$}
\hbox{:order {\it order\/} $\vert$}
\hbox{:required {\it boolean\/}}}}
\Vskip1pc!\null

\label Arguments:

In both the short and long forms, {\it name\/} is a symbol.  By convention,
non-keyword, non-{\bf nil} symbols are usually used.

\vfill\eject
\label Arguments of the Short Form:

The short form syntax of {\bf define-method-combination} is recognized
when the second subform is a non-{\bf nil} symbol or is not present.
When the short form is used, {\it name\/} is defined as a type of
method combination that produces a Lisp form {\tt ({\it operator
method-call method-call $\ldots$ })}.  The {\it operator\/} is a symbol
that can be the name of a function, macro, or special form.  The
{\it operator\/} can be specified by a keyword option; it defaults to {\it
name}.

Keyword options for the short form are the following:

\beginlist

\item{\bull}
The {\bf :documentation} option is used to document the method-combination type.

\item{\bull}
The {\bf :identity-with-one-argument} option enables an optimization
when {\it boolean\/} is true (the default is false).  If there is
exactly one applicable method and it is a primary method, that method
serves as the effective method and {\it operator\/} is not called.
This optimization avoids the need to create a new effective method and
avoids the overhead of a function call.  This option is designed to be
used with operators such as {\bf progn}, {\bf and}, {\bf $+$}, and
{\bf max}.

\item{\bull}
The {\bf :operator} option specifies the name of the operator.  The
{\it operator\/} argument is a symbol that can be the name of a
function, macro, or special form.  By convention, {\it name\/} and
{\it operator\/} are often the same symbol.  This is the default,
but it is not required.

\endlist

None of the subforms is evaluated.

These types of method combination require exactly one qualifier per
method.  An error is signaled if there are applicable methods with no
qualifiers or with qualifiers that are not supported by the method
combination type. 

A method combination procedure defined in this way recognizes two
roles for methods.  A method whose one qualifier is the symbol naming
this type of method combination is defined to be a primary method.  At
least one primary method must be applicable or an error is signaled.
A method with {\bf :around} as its one qualifier is an auxiliary
method that behaves the same as a {\bf :around} method in standard
method combination.  The function {\bf call-next-method} can only be
used in {\bf :around} methods; it cannot be used in primary methods
defined by the short form of the {\bf define-method-combination} macro.

A method combination procedure defined in this way accepts an optional
argument named {\it order}, which defaults to {\bf
:most-specific-first}.  A value of {\bf :most-specific-last} reverses
the order of the primary methods without affecting the order of the
auxiliary methods.

The short form automatically includes error checking and support for
{\bf :around} methods.

For a discussion of built-in method combination types, see the section
``Built-in Method Combination Types.''

\vfill\eject
\label Arguments of the Long Form:

The long form syntax of {\bf define-method-combination} is recognized 
when the second subform is a list.  

The {\it lambda-list\/} argument is an ordinary lambda-list.  It
receives any arguments provided after the name of the method
combination type in the {\bf :method-combination} option to {\bf
defgeneric}.

A list of method group specifiers follows.  Each specifier selects a subset
of the applicable methods to play a particular role, either by matching
their qualifiers against some patterns or by testing their qualifiers with
a predicate.   These method group specifiers define all method qualifiers
that can be used with this type of method combination.  If an applicable 
method does not fall into any method group, the system signals the error
that the method is invalid for the kind of method combination in use.

Each method group specifier names a variable.  During the execution of
the forms in the body of {\bf define-method-combination}, this
variable is bound to a list of the methods in the method group.  The
methods in this list occur in most-specific-first order.

A qualifier pattern is a list or the symbol {\bf *}.  A method matches
a qualifier pattern if the method's list of qualifiers is {\bf equal}
to the qualifier pattern (except that the symbol {\bf *} in a qualifier
pattern matches anything).  Thus a qualifier pattern can be one of the
following: the empty list {\bf ()}, which matches unqualified methods;
the symbol {\bf *}, which matches all methods; a true list, which
matches methods with the same number of qualifiers as the length of
the list when each qualifier matches the corresponding list element;
or a dotted list that ends in the symbol {\bf *} (the {\bf *} matches
any number of additional qualifiers).


Each applicable method is tested against the qualifier patterns and
predicates in left-to-right order.  As soon as a qualifier pattern matches
or a predicate returns true, the method becomes a member of the
corresponding method group and no further tests are made.  Thus if a method
could be a member of more than one method group, it joins only the first
such group.  If a method group has more than one qualifier pattern, a
method need only satisfy one of the qualifier patterns to be a member of
the group.

The name of a predicate function can appear instead of qualifier
patterns in a method group specifier.  The predicate is called for
each method that has not been assigned to an earlier method group; it
is called with one argument, the method's qualifier list.  The
predicate should return true if the method is to be a member of the
method group.  A predicate can be distinguished from a qualifier pattern
because it is a symbol other than {\bf nil} or {\bf *}.

If there is an applicable method whose qualifiers are not valid
for the method combination type, the function {\bf invalid-method-error}
is called.

Method group specifiers can have keyword options following the
qualifier patterns or predicate.  Keyword options can be distinguished from
additional qualifier patterns because they are neither lists nor the symbol
{\bf *}.  The keyword options are as follows:

\beginlist

\item{\bull}
The {\bf :description} option is used to provide a description of the
role of methods in the method group.  Programming environment tools
use {\tt (apply \#'format stream {\it format-string\/}
(method-qualifiers {\it method\/}))} to print this description, which
is expected to be concise.  This keyword
option allows the description of a method qualifier to be defined in
the same module that defines the meaning of the method
qualifier.  In most cases, {\it format-string\/} will not contain any
format directives, but they are available for generality.  If {\bf
:description} is not specified, a default description is generated
based on the variable name and the qualifier patterns and on whether
this method group includes the unqualified methods.  The argument {\it
format-string\/} is not evaluated.

\item{\bull}
The {\bf :order} option specifies the order of methods.  The {\it
order\/} argument is a form that evaluates to {\bf
:most-specific-first} or {\bf :most-specific-last}.  If it evaluates
to any other value, an error is signaled.  This keyword option is a
convenience and does not add any expressive power.
If {\bf :order} is not specified, it defaults to {\bf :most-specific-first}.

\item{\bull}
The {\bf :required} option specifies whether at least one method in
this method group is required.  If the {\it boolean\/} argument is
non-{\bf nil} and the method group is empty (that is, no applicable
methods match the qualifier patterns or satisfy the predicate), an
error is signaled.  This keyword option is a convenience and does not
add any expressive power.  If {\bf :required} is not specified,
it defaults to {\bf nil}.  The {\it boolean\/} argument is not
evaluated.

\endlist

The use of method group specifiers provides a convenient syntax to
select methods, to divide them among the possible roles, and to perform the
necessary error checking.  It is possible to perform further filtering
of methods in the body forms by using normal list-processing operations
and the functions {\bf method-qualifiers} and {\bf
invalid-method-error}.  It is permissible to use {\bf setq} on the
variables named in the method group specifiers and to bind additional
variables.  It is also possible to bypass the method group specifier
mechanism and do everything in the body forms.  This is accomplished
by writing a single method group with {\bf *} as its only qualifier
pattern; the variable is then bound to a list of all of the applicable
methods, in most-specific-first order.

The body {\it forms\/} compute and return the Lisp form that specifies
how the methods are combined, that is, the effective method.  The
effective method uses the macro {\bf call-method}.  This macro has
lexical scope and is available only in an effective method form.
Given a method object in one of the lists produced by the method group
specifiers and a list of next methods, the macro {\bf call-method}
will invoke the method such that {\bf call-next-method} has available
the next methods.

When an effective method has no effect other than to call a single
method, some implementations employ an optimization that uses the
single method directly as the effective method, thus avoiding the need
to create a new effective method.  This optimization is active when
the effective method form consists entirely of an invocation of
the {\bf call-method} macro whose first subform is a method object and
whose second subform is {\bf nil}.  Each {\bf
define-method-combination} body is responsible for stripping off
redundant invocations of {\bf progn}, {\bf and}, {\bf
multiple-value-prog1}, and the like, if this optimization is desired.

\vfill\eject
The list {\tt (:arguments . {\it lambda-list\/})} can appear before
any declarations or documentation string.  This form is useful when
the method combination type performs some specific behavior as part of
the combined method and that behavior needs access to the arguments to
the generic function.  Each parameter variable defined by {\it
lambda-list\/} is bound to a form that can be inserted into the
effective method.  When this form is evaluated during execution of the
effective method, its value is the corresponding argument to the
generic function.  If {\it lambda-list\/} is not congruent to the
generic function's lambda-list, additional ignored parameters are
automatically inserted until it is congruent.  Thus it is permissible
for {\it lambda-list\/} to receive fewer arguments than the number
that the generic function expects.
 
Erroneous conditions detected by the body should be reported with
{\bf method-combination-error} or {\bf invalid-method-error}; these functions
add any necessary contextual information to the error message and will
signal the appropriate error.

The body {\it forms\/} are evaluated inside of the bindings created by the
lambda-list and method group specifiers.  Declarations at the head of
the body are positioned directly inside of bindings created by the
lambda-list and outside of the bindings of the method group variables. 
Thus method group variables cannot be declared.

Within the body {\it forms\/}, {\it generic-function-symbol}
is bound to the generic function object.

%End Part 3 of 8 functi.tex